Define the messy zone

Define the messy zone: benefits

• Being explicit about where the mess is allowed us to focus on simplifying and clarifying the internals
• Higher level code functioned as expected
• Didn’t have to commit to the structure of the function parameters initially
• We could work that out naturally as the code evolved
• Clear markers of where we would need to clean up later, - Avoided the issue of forgetting to change parameters everywhere

Define the messy zone example

example = function(arg1, arg2) {
# Messy zone

a_better_name = arg1$mess$ugh
helpful_name = arg2$what$is$this

# Refactor the internals

useful_result = a_better_name + helpful_name
sensible_name_tibble = a_better_name * helpful_name    

# Messy Zone
results$some$mess = useful_result
results$another$naff$list = sensible_name_tibble

}

Push the mess up

Start with a blank slate

• Avoid the temptation to copy-paste
• Can tie you to the old style

Take time to design

Jane and I had one session where we didn’t touch any code at all. We talked, doodled and drew diagrams. You might leave a session like this feeling a little deflated that you didn’t achieve anything. However, that session was actually the most valuable. In the following session we made huge progress, because we had already done the hard work of thinking out the design fully. We were able to whizz through the functions, implementing our new design efficiently. We found ourselves constantly referring back to the diagrams to remind ourselves of the design choices we had made.

My favourite tools:

• Miro board
• draw.io
• excalidraw

A good name goes a long way

We all know that it’s important to choose good names for parameters and functions. However, in this project, I was surprised just how much of a difference a good name makes. Sometimes, the only thing we would change in a function would be the names. Often a simple rename morphed the unintelligible code in front of me into a clear, readable explanation of the approach.

# Example

Test regularly

• Things will go wrong

• Deleted code

• Brackets

• You want to know as soon as possible

• Ensure that your code is always run-able

• Check your code still works by running your tests - {testthat}

• Statistical models must ensure numerical results are unaffected by the refactor

• CI/CD

Why rather than How

The code was initially what I would call “How” programming. The different components of the functions were grouped by how the calculations were computed programmatically rather than why we were calculating them. This made it hard for someone new to the code to understand what each function did.

I’m not an environmental scientist, so I don’t understand all of the science behind Jane’s complex model. However, by asking questions about what she was trying to achieve, we re-grouped the different stages of each function in terms of the science, rather than the implementation. Changing focus of the code to the scientific method made it much clearer to follow.

Do it with a friend

Top tips

1. Define the messy zone

2. Push the mess up

3. Start with a blank slate

4. Take time to design

5. A good name goes a long way

6. Test regularly

7. Why rather than How

8. Do it with a friend